UX Guideline: add responsive table layout and agentic UX style by hyoshis · Pull Request #9239 · Azure/azure-dev

hyoshis · 2026-07-21T21:42:41Z

Adds two sets of UX guidance to the azd style guides:

Responsive list/table layouts for list commands, documented as part of the core azd design patterns in azd-style-guide.md.
Agentic (AI / GitHub Copilot) UX patterns, moved into a dedicated agentic-ux-style-guide.md so the core guide focuses solely on core azd design patterns (which extensions may follow for consistency, but are not enforced).

Adds cross-references in the core guide's overview and in cli/azd/AGENTS.md so agents reference the correct file for the flow they're working on.

Adds two sets of UX guidance to the azd style guides: 1. Responsive list/table layouts for list commands, documented as part of the core azd design patterns in azd-style-guide.md. 2. Agentic (AI / GitHub Copilot) UX patterns, moved into a dedicated agentic-ux-style-guide.md so the core guide focuses solely on core azd design patterns (which extensions may follow for consistency, but are not enforced). Adds cross-references in the core guide's overview and in cli/azd/AGENTS.md so agents reference the correct file for the flow they're working on. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 656aee2e-29aa-4b53-965c-63543c1dd44a

github-actions · 2026-07-21T21:42:57Z

🔗 Linked Issue Required

Thanks for the contribution! Please link a GitHub issue to this PR by adding Fixes #123 to the description or using the sidebar.
No issue yet? Feel free to create one!

azure-pipelines · 2026-07-21T21:42:58Z

Azure Pipelines: 22 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

Adds authoritative guidance for responsive CLI tables and agentic UX.

Changes:

Documents responsive table layouts and conventions.
Adds a dedicated agentic UX style guide.
Directs agents to the appropriate UX guide.

Show a summary per file

File	Description
`cli/azd/docs/style-guidelines/azd-style-guide.md`	Adds responsive table guidance.
`cli/azd/docs/style-guidelines/agentic-ux-style-guide.md`	Defines agentic visual patterns.
`cli/azd/AGENTS.md`	Adds guide-selection instructions.

Review details

Comments suppressed due to low confidence (2)

cli/azd/docs/style-guidelines/azd-style-guide.md:403

[azd-code-reviewer] The full example has six data columns, while this compact example shows four and hides the remaining two. Since the formatter reports visible versus total defined columns, the hint should say “4 of 6,” not “4 of 5.”

Showing 4 of 5 columns. Resize the terminal or run with -o json for full details.

cli/azd/docs/style-guidelines/agentic-ux-style-guide.md:96

[azd-code-reviewer] This color summary says “hints” are gray, which conflicts with line 28’s statement that shared WithHintFormat hints are magenta. Name the gray element as the cancel affordance and explicitly preserve the shared hint color so the guide gives one unambiguous rule.

> Colors: `◆` and the subagent/tool names → magenta (`color.MagentaString`). `✔︎` → green. `✖` and error detail → red. Reasoning, sub-detail (`├`/`└`), and hints → gray. `◇ Using skill:` → cyan. Assistant prose → `WithMarkdown`.

Files reviewed: 3/3 changed files
Comments generated: 2
Review effort level: Medium

+    {
+        Column:      output.Column{Heading: "STATUS", ValueTemplate: "{{.Status}}"},
+        Priority:    1,
+        ColorFunc:   extensionStatusColor, // semantic status color
+    },
+}


+| Subagent completed name      | `✔︎ <subagent> completed` — name magenta (check green) | `SessionEventTypeSubagentCompleted` |
+| Init "preparing" message     | `Preparing application for Azure deployment...` magenta | `cmd/init.go` |
+
+Reserve **direct `color.MagentaString`** styling for these agent-identity / active-AI-work cases. Do not magenta-color arbitrary text. (Shared `WithHintFormat` hints are a separate, allowed use of magenta.)


jongio

Two small consistency nits in the new guides, both checked against the source.

jongio · 2026-07-21T22:24:03Z

+────────────────────────────────────────────────────────────────────────────────────────
+az-cli              Azure CLI                      Up to date         1.0.0
+
+Showing 4 of 5 columns. Resize the terminal or run with -o json for full details.


The full-table example above shows six columns (ID, NAME, STATUS, INSTALLED, LATEST, SOURCE); compact drops LATEST and SOURCE, so this hint should read 4 of 6, not 4 of 5.

Suggested change

Showing 4 of 5 columns. Resize the terminal or run with -o json for full details.

Showing 4 of 6 columns. Resize the terminal or run with -o json for full details.

jongio · 2026-07-21T22:24:03Z

+✔︎ GitHub Copilot completed
+```
+
+> Colors: `◆` and the subagent/tool names → magenta (`color.MagentaString`). `✔︎` → green. `✖` and error detail → red. Reasoning, sub-detail (`├`/`└`), and hints → gray. `◇ Using skill:` → cyan. Assistant prose → `WithMarkdown`.


This line lists hints as gray, but WithHintFormat maps to color.MagentaString in pkg/output/colors.go, and the section above calls the shared hint color magenta. The gray elements are the reasoning text, the ├/└ sub-detail lines, and the Press Ctrl+C to cancel affordance. Drop hints from the gray list (and name the cancel affordance instead) so the summary doesn't contradict the magenta-hint rule stated earlier in the file.

richardpark-msft

Nothing huge, but just some areas that might need clarification, or are duplicating commentary we should probably put in code.

richardpark-msft · 2026-07-21T23:12:17Z

+
+Commands that print a list of items — `azd tool list`, `azd tool check`, `azd extension list` (and its alias `azd ext list`), `azd extension source list`, `azd template list`, `azd template source list`, `azd copilot consent list` — render through the shared responsive formatter rather than hand-rolling their own `tabwriter` output. This keeps column names, colors, and layout behavior consistent, and gives every list command a layout that adapts to the terminal width.
+
+**Any new or migrated list command MUST use this formatter.** A few legacy commands (e.g. `azd env list`, which still uses the plain `TableFormatter`) predate it — migrate them when touched rather than adding another bespoke table.


Suggested change

**Any new or migrated list command MUST use this formatter.** A few legacy commands (e.g. `azd env list`, which still uses the plain `TableFormatter`) predate it — migrate them when touched rather than adding another bespoke table.

**Any new or migrated list command MUST use this formatter.**

I would just remove the bit about legacy commands. We should just file issues to move them over instead - this bit in the doc would just get stale over time, and the "new or migrated commands" bit covers your point well enough.

richardpark-msft · 2026-07-21T23:14:20Z

@@ -0,0 +1,104 @@
+# Azure Developer CLI (`azd`) Agentic UX Style Guide


This is a pretty dense guide, but it makes sense.

When I'm reading it, I'm wondering if we're just missing some nice wrapper utils, or something that'll make sure we consistently apply the right policies when we're in the agentic flow. From what you've got below, it sounds like most of it is manual at the moment.

It's excellent to see it documented though, and hopefully (over time) we can chip away at this doc because it'll become enforced in the system.

richardpark-msft · 2026-07-21T23:17:59Z

+```
+  ...streamed reasoning text (dim gray)...
+
+  / Thinking...


Okay, I'm curious - what is your stance on using emojis for some of these? (🧠)

I've heard that it can be less than useful for some cases, like for people that are using screen readers, but I wondered the same about progress/spinners as well.

richardpark-msft · 2026-07-21T23:18:57Z

+**Tool run and completion:**
+
+```
+Running powershell go build...


Not sure if it should go in this doc, but there's a distinction between what the agent is saying it'll do, and the actual command that runs.

I'm assuming this text is always intended to be "what the agent says it will do". Are we supposed to (optionally) show the nitty gritty detail of the command that executed?

richardpark-msft · 2026-07-21T23:20:29Z

+
+```
+◆ GitHub Copilot
+  └ Generates Azure app scaffolding


I'm wondering if we should have an identifier for sub-agents, specifically because I've noticed other GitHub apps acquiring other "sub" things, like nested sessions.

richardpark-msft · 2026-07-21T23:32:25Z

+Each column is a `PrettyColumn` (a `Column` plus responsive metadata). Conventions:
+
+- **Headings are UPPERCASE** and short (`ID`, `NAME`, `STATUS`, `INSTALLED`, `LATEST`, `SOURCE`, `CATEGORY`, `TYPE`, `LOCATION`). Reuse these standard names across commands — don't introduce a synonym like `VERSION` when `INSTALLED`/`LATEST` already express the concept.
+- **`Priority`** controls compact visibility: `1` and `2` survive the compact breakpoint; `3+` are full-table only; `0` is treated as `1`. Keep the identifying columns (`ID`, `STATUS`, `INSTALLED`) at priority `1`.


If these field descriptions are just overlapping with the doc comments in the actual code we should just remove it. Agents can easily grab it from the code, and then we won't have stale docs.

richardpark-msft · 2026-07-21T23:33:08Z

+
+#### List Command Guidelines
+
+- **Always support `-o json`.** The responsive layouts are for humans; scripts and full detail should use `--output json`. The compact hint explicitly points users there.


I'm still kind of sad we don't have a "run with -o wide" or similar like kubectl, if only because it means they still have a way to see more text in a human readable way.

richardpark-msft · 2026-07-21T23:34:30Z

+#### List Command Guidelines
+
+- **Always support `-o json`.** The responsive layouts are for humans; scripts and full detail should use `--output json`. The compact hint explicitly points users there.
+- **Empty state**: print a clear, single-line message instead of an empty table (e.g. `No tools found in the registry.`, `No tools found.`). Extension list adds guidance on how to add a source.


I'm assuming the empty message doesn't come from the table writer. Do we have a recommended function to print properly to the screen?

(I feel like @JeffreyCA just went through some headaches with this where we were not using a shared output writer, or something of that nature)

richardpark-msft · 2026-07-21T23:35:00Z

+
+- **Always support `-o json`.** The responsive layouts are for humans; scripts and full detail should use `--output json`. The compact hint explicitly points users there.
+- **Empty state**: print a clear, single-line message instead of an empty table (e.g. `No tools found in the registry.`, `No tools found.`). Extension list adds guidance on how to add a source.
+- **Stable ordering**: the formatter does not sort — it renders (and groups cards) in the order rows are passed in. **Sort your rows before formatting** and group by a stable key (`tool list` by `CATEGORY`, `extension list` by `SOURCE`) so output is deterministic.


What are 'cards' in this discussion?

richardpark-msft · 2026-07-21T23:35:53Z

+- **Always support `-o json`.** The responsive layouts are for humans; scripts and full detail should use `--output json`. The compact hint explicitly points users there.
+- **Empty state**: print a clear, single-line message instead of an empty table (e.g. `No tools found in the registry.`, `No tools found.`). Extension list adds guidance on how to add a source.
+- **Stable ordering**: the formatter does not sort — it renders (and groups cards) in the order rows are passed in. **Sort your rows before formatting** and group by a stable key (`tool list` by `CATEGORY`, `extension list` by `SOURCE`) so output is deterministic.
+- **Don't hand-roll a new table.** If you find yourself writing `tabwriter` for a list of items, use `PrettyTableFormatter` instead so the command inherits responsive behavior for free.


I think you can delete this line. You've made the case. :)

jongio

Verified all the code references in both guides against main - the constants, file paths, and color helpers all check out. Two small doc-accuracy nits from my earlier pass are still open (the compact-table column count and the hints color label), but neither blocks. Nice addition.

hyoshis self-assigned this Jul 21, 2026

Copilot AI review requested due to automatic review settings July 21, 2026 21:42

hyoshis requested review from JeffreyCA, RickWinter, hemarina, richardpark-msft, tg-msft and vhvb1989 as code owners July 21, 2026 21:42

hyoshis requested a review from kristenwomack July 21, 2026 21:43

Copilot started reviewing on behalf of hyoshis July 21, 2026 21:43 View session

github-actions Bot mentioned this pull request Jul 21, 2026

[aw] No-Op Runs #8415

Open

Copilot AI reviewed Jul 21, 2026

View reviewed changes

This was linked to issues Jul 21, 2026

[UX] Guideline: Document responsive table patterns in UX guideline #8671

Open

[UX] Guideline: Add agentic UX pattern to style MD file #7447

Open

jongio reviewed Jul 21, 2026

View reviewed changes

vhvb1989 approved these changes Jul 21, 2026

View reviewed changes

richardpark-msft reviewed Jul 21, 2026

View reviewed changes

jongio approved these changes Jul 22, 2026

View reviewed changes

	Showing 4 of 5 columns. Resize the terminal or run with -o json for full details.
	Showing 4 of 6 columns. Resize the terminal or run with -o json for full details.


		Commands that print a list of items — `azd tool list`, `azd tool check`, `azd extension list` (and its alias `azd ext list`), `azd extension source list`, `azd template list`, `azd template source list`, `azd copilot consent list` — render through the shared responsive formatter rather than hand-rolling their own `tabwriter` output. This keeps column names, colors, and layout behavior consistent, and gives every list command a layout that adapts to the terminal width.

		Any new or migrated list command MUST use this formatter. A few legacy commands (e.g. `azd env list`, which still uses the plain `TableFormatter`) predate it — migrate them when touched rather than adding another bespoke table.

		@@ -0,0 +1,104 @@
		# Azure Developer CLI (`azd`) Agentic UX Style Guide


		#### List Command Guidelines

		- Always support `-o json`. The responsive layouts are for humans; scripts and full detail should use `--output json`. The compact hint explicitly points users there.

Uh oh!

Conversation

hyoshis commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026

🔗 Linked Issue Required

Uh oh!

azure-pipelines Bot commented Jul 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardpark-msft left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jongio left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants